home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / net / bind-contrib.tar.gz / bind-contrib.tar / contrib / getkeyby / README < prev   
Encoding:
Text File  |  1996-10-25  |  5.8 KB  |  138 lines
  1.     getkeybyname() library release notes
  2.     Very Preliminary Release
  3.     John Gilmore, gnu@toad.com
  4.     September 3, 1996
  5.  
  6. This code is provided so you can try fitting it into your programs
  7. and see how well it integrates.  The interface may change before final
  8. release.
  9.  
  10. We provide a library routine, getkeybyname(), which permits cryptographic
  11. keys to be obtained from the Domain Name System from wherever people have
  12. published them.  This library routine is designed to be portable to
  13. many environments that include a domain resolver library (please send
  14. any changes that you have to make, back to me at gnu@toad.com).  You
  15. link this routine into your application, and it calls the resolver
  16. to do DNS queries.  It processes the results of the queries and returns
  17. the keys to your application in a convenient form.
  18.  
  19. Usage:
  20.  
  21.     count = getkeybyname(dnskeys, maxcount, options);
  22.  
  23.     dnskeys is a "struct dnskey *" which points to one or more
  24.     structures in which keys will be returned.  Maxcount is the
  25.     number of "struct dnskey"s pointed to by dnskeys.  Options
  26.     is a set of option flags; DNSKEYS_NO_OPTIONS is the default
  27.     value to pass.
  28.  
  29.     The first dnskey structure must have its dname, flags, protocol,
  30.     and algorithm fields set before the call:
  31.  
  32.         dname is a char * which points to a domain name,
  33.         e.g. "dnssec.toad.com".
  34.  
  35.         flags contains any DNS key flag bits which your
  36.         application requires to be on.  Only keys in which
  37.         these bits are set will be returned.  Zero is the
  38.         default value.  See the DNS Security RFC for details.
  39.  
  40.         protocol specifies what DNS protocol field values 
  41.         your application requires.  Zero is the default
  42.         value, permitting any protocol.  See the DNS Security
  43.         RFC for details.
  44.  
  45.         algorithm specifies what DNS algorithm type your
  46.         application requires.  Zero is the default value,
  47.         permitting any algorithm.  See the DNS Security
  48.         RFC for details.
  49.  
  50.     ALL of the dnskey structures must have their keylen (and, if
  51.     nonzero, key) fields initialized.  If keylen is nonzero, key is
  52.     assumed to point to pre-allocated memory of that length, where
  53.     a key will be returned (and keylen will be set to its actual
  54.     length).  If keylen is zero, memory will be allocated with
  55.     malloc() for any key returned in that structure, and its length
  56.     will be stored into keylen.  It is the caller's responsibility
  57.     to free this memory.
  58.  
  59.     The returned value, count, is negative if an error occurs, and
  60.     an error code is returned in h_errno (as is usual for DNS
  61.     resolver subroutines).  The returned value is zero if no keys
  62.     were published at that domain name (which match your specified
  63.     criteria).  If the return value is positive, it says how many
  64.     dnskey structures have been filled in with valid key
  65.     information.  The dnskey structures beyond the count have not
  66.     been altered.
  67.  
  68.     The getkeybyname() routine contains an internal select() loop
  69.     and may result in significant delay -- seconds or minutes --
  70.     particularly when the domain being queried is not reachable on
  71.     the Internet at that moment.  A suggestion for your user
  72.     interface is that you let your user know before you call it,
  73.     and when it returns, so that they will understand what the
  74.     problem is if there is a significant hang.  In a text-based
  75.     interface, a message like "Getting key for dnssec.toad.com..."
  76.     then "OK.\n" would be great.
  77.  
  78.     In the future I hope to have an asynchronous interface to 
  79.     it, which would permit you to include it in your own select()
  80.     loop so that your application remains interactive during the
  81.     potentially lengthy lookup process.  If your application needs
  82.     this, please let me know what kind of interface you would
  83.     like to see.
  84.  
  85. ******
  86.  
  87. The "getkey" program
  88.  
  89. Getkey.c is a very simple program for testing the getkeybyname() interface.
  90. If you run `getkey dnssec.toad.com' you will get and print all the keys
  91. for that domain address.  Run it against "frodo.dnssec.toad.com" to see
  92. several keys with different protocol and algorithm numbers.
  93.  
  94.  
  95. ******
  96.  
  97. In order to use DNS keying in your applications, you will need to:
  98.  
  99.   (0)  Define how to map the entities that your application cares about
  100. (e.g. users or hosts) into Domain Name System names.  Hosts are
  101. straightforward.  User email addresses have a proposed mapping in the
  102. Secure DNS RFC, such that e.g. "gnu@toad.com" becomes "gnu.toad.com".
  103.  
  104.   (1)  Define a format for storing the public keys used by your
  105. application in DNS Resource Records, if an existing published format is
  106. not already suitable.  Be sure to require key flag bit #5 to be set if
  107. your mapping is for a user name, or bit #6 if your mapping is for a
  108. host or similar entity.  Publish this format (and the name
  109. mapping above) as an Internet-Draft, and get an algorithm number
  110. assigned for it by the Internet Assigned Numbers Authority
  111. (IANA@usc-isi.edu).  Today, the two existing published formats are for
  112. raw RSA public key values, and for X.500 Objects with an Object ID
  113. number.
  114.  
  115.   (2)  Write code as part of your application that permits public keys
  116. to be output as textual DNS Resource Records in the format defined above.
  117. Document for your users how to give these resource records to their
  118. system administrator to be inserted into their domain's published
  119. DNS records.  An example output resource record might be:
  120.  
  121.     dnssec.toad.com.    10000    KEY    0x0140 255 1 (
  122.         AQPAdr+bHGqBNfAQEvGLepslJQbt9Qu4iyAZ6FQIEjFtxcfv5GjSLY8/kLTEBGbC
  123.         p3xQsSK1jdbcevovOcEB5qnNF3C6IjNxs/HlVW9IS7/SMQ== )
  124.  
  125.   (3)  Write code as part of your application that permits public keys
  126. to be retrieved as DNS Resource Records in the format defined above.
  127.  
  128. You're done -- you have a worldwide global replicated high-availability
  129. cached high-performance distributed database for your keys.  Congratulations!
  130.  
  131.  
  132. References:
  133.  
  134. Domain Name System Security Extensions, Internet-Draft
  135. draft-ietf-dnssec-secext-10.txt, included in this distribution.
  136. Also available wherever Internet-Drafts are found.  This will
  137. become the DNS Security RFC when the RFC Editor is done with it.
  138.